Developer Documentation

QuickTime 4 API Documentation

Inside Macintosh: Imaging with QuickDraw

Previous | Chapter Top | Chapter Contents | Next |

Changing the Pixel Depth for a Video Device

The Monitors control panel is the user interface for changing the pixel depth, color capabilities, and positions of video devices. Since the user can control the capabilities of the video device, your application should be flexible: although it may have a preferred pixel depth, your application should do its best to accommodate less than ideal conditions.

If it is absolutely necessary for your application to draw on a video device of a specific pixel depth, your application can use the SetDepth function to change its pixel depth. Before calling SetDepth , use the HasDepth function to determine whether the available hardware can support the pixel depth you require.

HasDepth

To determine whether a video device supports a specific pixel depth, you can use the HasDepth function.

FUNCTION HasDepth (aDevice: GDHandle; depth: Integer;
                                         whichFlags: Integer; flags: Integer): Integer;
aDevice
A handle to the GDevice record of the video device.
depth
The pixel depth for which you're testing.
whichFlags
The gdDevType constant, which represents a bit in the gdFlags field of the GDevice record. (If this bit is set to 0 in the GDevice record, the video device is black and white; if the bit is set to 1, the device supports color.)
flags
The value 0 or 1. If you pass 0 in this parameter, the HasDepth function tests whether the video device is black and white; if you pass 1 in this parameter, HasDepth tests whether the video device supports color.

DESCRIPTION

The HasDepth function checks whether the video device you specify in the aDevice parameter supports the pixel depth you specify in the depth parameter, and whether the device is black and white or color, whichever you specify in the flags parameter.

The HasDepth function returns 0 if the device does not support the depth you specify in the depth parameter or the display mode you specify in the flags parameter.

Any other value indicates that the device supports the specified depth and display mode. The function result contains the mode ID that QuickDraw passes to the video driver to set its pixel depth and to specify color or black and white. You can pass this mode ID in the depth parameter for the SetDepth function (described next) to set the graphics device to the pixel depth and display mode for which you tested.

SPECIAL CONSIDERATIONS

The HasDepth function may move or purge blocks of memory in the application heap. Your application should not call this function at interrupt time.

SEE ALSO

See Designing Cards and Drivers for the Macintosh Family , third edition, for more information about the device modes returned as a function result for HasDepth .

SetDepth

To change the pixel depth of a video device, use the SetDepth function.

FUNCTION SetDepth (aDevice: GDHandle; depth: Integer;
                                         whichFlags: Integer; flags: Integer): OSErr;
aDevice
A handle to the GDevice record of the video device whose pixel depth you wish to change.
depth
The mode ID returned by the HasDepth function (described in the previous section) indicating that the video device supports the desired pixel depth. Alternatively, you can pass the desired pixel depth directly in this parameter, although you should use the HasDepth function to ensure that the device supports this depth.
whichFlags
The gdDevType constant, which represents a bit in the gdFlags field of the GDevice record. (If this bit is set to 0 in the GDevice record, the video device is black and white; if the bit is set to 1, the device supports color.)
flags
The value 0 or 1. If you pass 0 in this parameter, the SetDepth function changes the video device to black and white; if you pass 1 in this parameter, SetDepth changes the video device to color.

DESCRIPTION

The SetDepth function sets the video device you specify in the aDevice parameter to the pixel depth you specify in the depth parameter, and it sets the device to either black and white or color as you specify in the flags parameter. You should use the HasDepth function to ensure that the video device supports the values you specify to SetDepth . The SetDepth returns zero if successful, or it returns a nonzero value if it cannot impose the desired depth and display mode on the requested device.

The SetDepth function does not change the 'scrn' resource; when the system is restarted, the original depth for this device is restored.

SPECIAL CONSIDERATIONS

Your application should use SetDepth only if your application can run on devices of a particular pixel depth and is unable to adapt to any other depth. Your application should display a dialog box that offers the user a choice between changing to that depth or canceling display of the image before your application uses SetDepth . Such a dialog box saves the user the trouble of going to the Monitors control panel before returning to your application.

The SetDepth function may move or purge blocks of memory in the application heap. Your application should not call this function at interrupt time.

SEE ALSO

See the chapter "Dialog Manager" in Inside Macintosh: Macintosh Toolbox Essentials for information about creating and using dialog boxes.

© 1997 Apple Computer, Inc.

Previous | Chapter Top | Chapter Contents | Next